home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Format CD 52
/
Amiga Format AFCD52 (Issue 136, May 2000).iso
/
-in_the_mag-
/
workbench
/
adf
/
adflib
/
docs
/
api.txt
< prev
Wrap
Text File
|
2000-03-05
|
7KB
|
269 lines
The ADFlib API quick overview
*****************************
Always read ADFlib structures, never change a value directly, the
behaviour of the library could then become unforeseeable.
Minimal C program with ADFlib
-----------------------------
#include<stdio.h> /* for puts() */
#include"adflib.h"
ENV_DECLARATION;
int main(int argc, char *argv[])
{
adfEnvInitDefault();
puts("hello world");
adfEnvCleanUp();
}
Device
------
struct Device {
int devType; /* see adf_str.h */
BOOL readOnly;
long size; /* in bytes */
int nVol; /* partitions */
struct Volume** volList;
long cylinders; /* geometry */
long heads;
long sectors;
BOOL isNativeDev;
void *nativeDev;
};
struct Device* adfMountDev(char* name)
mounts and allocates a device (real or dump)
void adfDeviceInfo(struct Device* dev)
prints device info to stdout : must be rewritten for another GUI
void adfUnMountDev(struct Device* dev)
void adfCreateHd(struct Device* dev, int nbPartitions, struct Partition** part)
create a filesystem for harddisk with one or several partition
(see hd_test2.c)
void adfCreateFlop(struct Device* dev, char* name, int flags)
flags are for ffs, dircache or international (see fl_test.c)
Volume
------
struct Volume {
struct Device* dev;
SECTNUM firstBlock; /* first block of data area (from beginning of device) */
SECTNUM lastBlock; /* last block of data area (from beginning of device) */
SECTNUM rootBlock; /* root block (from firstBlock) */
char dosType; /* FFS/OFS, DIRCACHE, INTERNATIONAL */
BOOL bootCode;
int datablockSize; /* 488 or 512 */
char *volName;
long bitmapSize; /* in blocks */
SECTNUM *bitmapBlocks; /* bitmap blocks pointers */
struct bBitmapBlock **bitmapTable;
BOOL *bitmapBlocksChg;
SECTNUM curDirPtr;
};
struct Volume* adfMount(struct Device* dev, int partition, BOOL readOnly)
The first partition is #0
To be called after adfCreateFlop(), adfCreateHd() or adfMountDev().
void adfVolumeInfo(vol)
Display volume info to stdout, must be rewritten for another GUI
void adfUnMount(struct Volume *vol)
Dump device (.ADF)
------------------
struct adfCreateDumpDevice(char*, int cyl, int heads, int sectors)
To be used in place of adfMountDev(). Create a filename of the right size,
nothing else
File
----
struct File* adfOpenFile(struct Volume *volume, char* filename, char* mode)
mode = "r" or "w"
void adfCloseFile(struct File* file)
long adfReadFile(struct File* file, long length, unsigned char* buffer)
returns the number of bytes read
long adfWriteFile(struct File* file, long length, unsigned char* buffer)
returns the number of bytes written
BOOL adfEndOfFile(struct File* file)
Directory
---------
struct List* adfGetDirEnt(struct Volume* vol, SECTNUM nSect)
Returns a linked list with the directory entries. Each cell content of the list
must be freed with adfFreeEntry()
void adfFreeEntry(struct Entry *entry)
SECTNUM adfChangeDir(struct Volume* vol, char* dirname)
change current directory
void adfParentDir(struct Volume* vol)
change current directory
void printEntry(struct Entry* entry)
print the cell content to stdout
void CreateDir(struct Volume* vol, SECTNUM parentSect, char* name)
Callbacks mechanism
-------------------
* The library environment : 'struct Env adfEnv'
This variable is the only global variable of the library. It contains
callbacks for error and notification messages, and global variables.
By default, adfEnvInitDefault() initialize adfEnv functions that display
messages to stderr. You must use adfSetEnv() to use your own defined
functions.
The environment must be clean up with adfEnvCleanUp().
Four functions are available :
- (*adfEnv.eFct)(char*), called by ADFlib for a fatal error. It STOPS
the library : you must redefine yourself a more friendly to handle
this kind of error.
- (adfEnv.wFct)(char*), called for warnings. It is called when something wrong
happens, but processing can continue.
- (adfEnv.vFct)(char*), called to display verbose messages.
- (*adfEnv.notifyEnv)(SECTNUM p, int t), called to tell that
the volume structure has changed. The value p give where the change appeared,
t the type of the value (ST_DIR,ST_FILE,...).
The environment also contains access to nativeFunctions.
* Native device and functions
By default, the library is compiled to manage .ADF files (dump files) and
real devices like harddisk and removable disks (called native devives)
on ONE defined plateform (WinNT/Intel or Linux/68k...)
To add a new plateform to be supported by ADFlib, you must write your
own files adf_nativ.h and adf_nativ.c.
. data types
adf_nativ.h defines two structures :
- 'struct nativeDev'. It contains all the variable necessary for
the native device management. You can add here whatever you what to
be able to manage your real device on your plateform !
- 'struct nativeFunctions'. It defines the minimal API between ADFlib and
the specific native part. The functions names and prototypes must not be
changed, since they are called by the library. It is possible to add
other functions.
The type device 'struct Device' contains one variable 'void* nativeDev'.
It is allocated within adf_nativ.c by adfInitDevice().
Another variable 'BOOL isNativeDev' tells if the ADFlib is working with
a dump file (.ADF) or a real device.
'adfEnv' contains one variable 'void *nativeFct'. adfEnvInitDefault()
allocates it by calling the function adfInitNativeFct().
. callback functions :
The structure 'struct nativeFunctions' must have at least :
BOOL (*adfInitDevice)(struct Device*, char*)
BOOL (*adfNativeReadSector)(struct Device*, long, int, unsigned char*)
BOOL (*adfNativeWriteSector)(struct Device*, long, int, unsigned char*)
BOOL (*adfIsDevNative)(char*)
void (*adfReleaseDevice)()
For example, adfMountDev() calls adfInitDevice() this way :
struct nativeFunctions *nFct;
... /* struct Device* dev allocation */
nFct = adfEnv.nativeFct; /* was of type void* */
/* only once ! */
dev->isNativeDev = (*nFct->adfIsDevNative)(filename);
/* choose between dump or a real device */
if (dev->isNativeDev)
(*nFct->adfInitDevice)(dev, filename);
else
adfInitDumpDevice(dev, filename);
You must define one function to initialize a device, for example :
BOOL myInitDevice(struct Device *dev, char* name)
{
/* allocate and initailize dev->nativeDev */
/* return TRUE if everything happens right */
}
or
BOOL myIsDevNative(char* name)
{
/* for a Unix like platform */
return( strncmp("/dev/",name,5)==0 );
}
And so on to read, write a 512 bytes block, and release the native device.
The function 'adfInitNativeFct()', also defined in adf_nativ.c (and .h),
makes the names and the ADFlib native API :
void adfInitNativeFct()
{
struct nativeFunctions *nFct;
nFct = (struct nativeFunctions*)adfEnv.nativeFct;
nFct->adfInitDevice = myInitDevice ;
nFct->adfNativeReadSector = myReadSector ;
...
}
But the prototypes must stay the same !